home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / ARGONET / PD / SOUND / TIMPLAYER.ZIP / ReadMe next >
Text File  |  1998-03-23  |  8KB  |  237 lines
  1. This is my first alpha release of the TimPlayer module.
  2.  
  3. TimPlayer is a soundtrack player that currently supports the following formats:
  4.  
  5. - standard MODs
  6. - PC MODs (with more than 4 channels, already found a 28 channels one)
  7. - S3M (ADPCM samples and adlib samples not supported)
  8. - ITs (a few) with no instrument mode, no packed samples (v 214 and above)
  9.  
  10. planned (top priority):
  11. - instrument mode and envelopes, which means more ITs and XM.
  12. - saving songs as WAVs, usefull for slow machines.
  13. - support for 16-bit hardware (SWIs description and tester required).
  14.  
  15.  
  16. !DigitalCD has been setup to use TimPlayer for the relevant file types, so start
  17. DigitalCD and drop your files on it's music files control pannel. Should you
  18. experience problems then remove every 'tim' entry in the file !DigitalCD.Setup
  19. and !DigitalCD will use the good old trusted modules.
  20.  
  21. While playing you can run the View program which provides a little visualisation
  22. of the music (N.B.: it's for RISC OS >= 3.5 only).
  23.  
  24. The main features are turned toward sound quality rather than speed:
  25. - internal usage of 16-bit linear buffers mapped after mixing in 8-bit log
  26.   buffers using all the significant bits: 12 instead of the usual 8-bit table
  27.   (quiet sounds are much clearer).
  28. - no multiplications approximated by shifts
  29. - sample interpolation
  30. - mixing of up to 64 channels
  31. - patterns with up to 256 rows
  32. - support for multiple effects on the same channel
  33. - timing of song position and length
  34. - Precalculated Gain Control (an attempt to boost the sound of to quiet songs)
  35.  
  36.  
  37. Before you start using TimPlayer a few words of warning first:
  38. - all I know is that it works on my SA RPC with 8-bit sound hardware (reports
  39.   for other setups are very welcome).
  40. - loading of songs can be quite slow due to byte by byte reading of patterns
  41.   info, timing and PGC precalculations (which basically scan the whole patterns
  42.   as if playing to determine elapsed time and max sound amplitude).
  43. - those with less faster machine should be warned that the CPU usage can be
  44.   quite high: at 24us, a little above 1% of CPU per channel on my SA RPC
  45.               at 72us, Cache off, 4 channels grabs 80% of CPU
  46.   As a result playing songs with many channels on slow machines will result in
  47.   grabbing 100% of the CPU, you will never have the control back and be forced
  48.   to reset the machine (any code for controlling CPU usage is welcome).
  49. - it's my first attempt at writing a module and using sound DMA.
  50.  
  51.  
  52. I have noticed that altering the stereo position of hardware
  53. channels tends to produce noises (which often leads to
  54. a small bang when at song startup I switch from 1 to 8 channels
  55. and reconfigure the stereo positions). As anyone else
  56. experienced the same problems and/or found a solution to it?
  57.  
  58.  
  59. You can contact me using email at:
  60.  
  61. tim@swn.sni.be (which I can only access between Monday and Thursday).
  62.  
  63. or using smail address:
  64. Timmermans André
  65. Rue du Vert Coron, 17
  66. 7600 Péruwelz
  67. Belgium
  68.  
  69. --------------------------------------------------------------------------------
  70.  
  71. SWI Interface
  72. =============
  73.  
  74. Ok, it's alpha, so SWIs are subject to change and descriptions
  75. are minimalistic.
  76.  
  77. TimPlayer_Load &51380
  78. ---------------------
  79.  
  80. In  - R0 filename pointer
  81.  
  82. Out -
  83.  
  84. TimPlayer_Play &51381
  85. ---------------------
  86.  
  87. In  -
  88.  
  89. Out -
  90.  
  91. TimPlayer_Pause &51382
  92. ----------------------
  93.  
  94. In  -
  95.  
  96. Out -
  97.  
  98. TimPlayer_Stop &51383
  99. ---------------------
  100.  
  101. In  -
  102.  
  103. Out -
  104.  
  105. Removes also the song from memory.
  106.  
  107. TimPlayer_Position &51384
  108. -------------------------
  109.  
  110. In  - R0 new Sequence Position, -1 to read
  111.  
  112. Out - R0 Sequence Position
  113.       R1 Current Row in Pattern
  114.       R2 Current Pattern
  115.       R3 Current Pattern Length
  116.       R4 Time Index (in ms)
  117.  
  118. TimPlayer_SongInfo &51385
  119. -------------------------
  120.  
  121. In  -
  122. Out - R0 song name ptr
  123.       R1 mod type ptr
  124.       R2 number of channels
  125.       R3 seq len
  126.       R4 min pitch
  127.       R5 max pitch
  128.       R6 16-bit buffers len
  129.       R7 Time Length (in ms)
  130.  
  131. TimPlayer_ChannelParams &51386
  132. ------------------------------
  133.  
  134. In  - R0 channel nr
  135.  
  136. Out - R1 16-bit buffer ptr
  137.       R2 instrument nr
  138.       R3 pitch
  139.       R4 buffer peak value [0,&7FFF]
  140.       R5 buffer mean value [0,&7FFF]
  141.       R6 panning [-127 (left), 127 (right)]
  142.  
  143. TimPlayer_Volume &51387
  144. -----------------------
  145.  
  146. In  - R0 new volume [0,256], -1 to read
  147.  
  148. Out - R0 current volume
  149.  
  150. TimPlayer_Configure &51388
  151. --------------------------
  152.  
  153. In  - R0 code
  154.     - R1 value, -1 to read
  155.  
  156. Out - R1 current value
  157.  
  158. R0 code:
  159.  0  - R1 = hardware speed [24-72 us]
  160.  
  161. TimPlayer_SongParams &51389
  162. ---------------------------
  163.  
  164. Out - R0 current speed
  165.     - R1 current tempo
  166.     - R2 current global volume
  167.  
  168. --------------------------------------------------------------------------------
  169.  
  170. Timing explained
  171. ================
  172.  
  173. Due to the nature of soundtracks, timing is not a straightforward issue.
  174. So first let me explain briefly how a soundtrack is played:
  175.  
  176. 1. A song is composed of a sequence of patterns which are played in turn.
  177.    Example the sequence 1-3-5-1-1-2 means play pattern nr 1, then pattern
  178.    nr 3 then nr 5, then nr 1 again, etc.
  179.  
  180. 2. Each pattern is divided in n rows (64 in general) which are played in turn.
  181.    A row contains information to apply to each defined channel: instrument,
  182.    note to play, volume, panning, commands (effects) to apply. When a row is
  183.    played, first the row is decoded, then commands are applyed and the note
  184.    is maintained for a given duration called a frame (or sometimes a tick).
  185.    Then commands are re-applyed and the note is maintained for the same
  186.    duration. Then ...
  187.  
  188.    The duration of a row is determined by two parameters:
  189.    - the Tempo or number of beats per minutes (125 by default)
  190.      and the relation: nr of frames/sec = 0.4 * tempo.
  191.    - the Speed or number of frames per row (6 by default).
  192.  
  193. So, the duration of a song could simply be:
  194.  
  195. sum for each pattern in the sequence of "nr of rows * speed * .4 * tempo".
  196.  
  197. The problem is the existence of special commands that interfers with this,
  198. such as:
  199.  
  200. - Set Tempo, to alter the tempo
  201. - Set Speed, to alter the speed
  202. - Pattern break, to stop playing the current pattern and to go
  203.   in row x of the next pattern in the sequence
  204. - Sequence Jump, to stop playing current pattern and to go
  205.   in row 0 of pattern at sequence index x.
  206. - Loop, to loop x times on a set of rows.
  207.  
  208. The best way I have found is to perform the song without actually playing
  209. but applying only the above commands, adding together the resulting
  210. frame durations and storing this time index at the start of each position
  211. in the pattern sequence until I reach a the end of a sequence or I branch
  212. to a sequence position I have already timed.
  213.  
  214. As this may not cover all the positions in the sequence (for example all
  215. the songs in the game Lemmings are stored in the same soundtrack and are
  216. played by moving to different looping sequence fragments) I then move
  217. to the first untimed sequence position and continue the timing from that
  218. point. And again and again until every sequence position is timed.
  219. The final timing obtained is the time length reported by TimPlayer_SongInfo.
  220.  
  221. During real playback I maintain a timer that can be obtained on return of
  222. TimPlayer_Position. The timer is reset at every sequence position change
  223. to the time index store for that position, then time is added normally
  224. while the pattern is played.
  225.  
  226. Those of you with some knowledge of how soundtracks works will noticed
  227. immediately the remaining problems:
  228.  
  229. - by combining Pattern Break and Sequence Jumps it is possible
  230.   to perform 2 or more sets of differents rows of the same pattern
  231.   position (and I have only timed one of them) or to perform
  232.   the same set with different tempo/speed settings.
  233.  
  234. - when the user decide to skip a part of the somg he may bypass
  235.   some Set Tempo/Set Speed, which means that the song will then
  236.   continue to play with abnormal tempo/speed settings.
  237.